Aminet 1/Aminet - June 1993 [Walnut Creek].iso/usenet/sources/volume91/utilitys/bmake_06/part03

Internet Message Format | 1991-07-04 | 18.2 KB

Path: news.larc.nasa.gov!amiga-request
From: [e-mail] (Amiga Sources/Binaries Moderator)
Subject: v91i125: bmake 0.6 - automate recompiling multiple source files, Part03/03
Reply-To: ENG  BENNY <[e-mail]>
Newsgroups: comp.sources.amiga
Message-ID: <[e-mail]>
References: <[e-mail]>
Date: 04 Jul 91 16:38:43 GMT
Approved: [e-mail] (Tad Guy)
X-Mail-Submissions-To: [e-mail]
X-Post-Discussions-To: comp.sys.amiga.misc

Submitted-by: ENG  BENNY <[e-mail]>
Posting-number: Volume 91, Issue 125
Archive-name: utilities/bmake-0.6/part03

#!/bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#        "End of archive 3 (of 3)."
# Contents:  bmake.doc
# Wrapped by tadguy@ab20 on Thu Jul  4 12:38:41 1991
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'bmake.doc' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'bmake.doc'\"
else
echo shar: Extracting \"'bmake.doc'\" \(16057 characters\)
sed "s/^X//" >'bmake.doc' <<'END_OF_FILE'
X
X                       Documentation For The Make Utility
X                           Copyright (c) 1991 by Ben Eng
X
X
XBen Eng
X150 Beverley St. Apt #1L
XToronto, Ontario
XM5T 1Y6
X
[e-mail]
XBIX: jetpen
X
X
XOVERVIEW
X
XMake is a programming utility used to automate the process of recompiling
Xmultiple interdependent source files into an output file, which is called
Xthe goal.  The rules for making the goal are explicitly stated in an input
Xfile called the Makefile, and implicitly determined from builtin inference
Xrules.  Normally, the Makefile for a goal is written so that the only thing
Xthat needs to be done to recompile newly modified source files is to run
Xthe Make program.
X
X
XMAKEFILE
X
XThe Makefile is a text file which is read by the Make program.  The
XMakefile is written to define the rules for making a goal up to date.  A
Xgoal file is up to date if it has a modification datestamp that is more
Xrecent than all of its dependents, after all dependents are made up to date
Xwith respect to their dependents.  This criterion for up to dateness is
Xapplied recursively, such that the most deep nested dependent will be made
Xbefore any target file that depends on it.
X
XHere is an example of a simple Makefile, that does not correspond to what
Xwould normally be used:
X
X# comment1
X# comment2
X
Xgoal: target.o ; command three
X
Xtarget.o: source.c header.h
X    command one
X    command two
X
X
XIn a Makefile, any line beginning with a `#' character is considered to be
Xa comment line.  Comment lines are ignored by the Make program.  Rules are
Xdefined by a line that begins with one or more target filenames, followed
Xby a colon, an optional list of dependent filenames, an optional semicolon
Xand an optional command.  Subsequent lines that begin with a tab character
Xare command lines associated with the rule; the next line that does not
Xbegin with a tab character indicates the end of the current rule and the
Xbeginning of a new rule.
X
XIn the above example, the Make program will read the Makefile and find the
Xfirst target filename to be ``goal''.  It will then attempt to make
X``goal'' up to date by first making its dependencies (namely, ``target.o'')
Xup to date.  In order to make ``target.o'' up to date, Make requires a rule
Xthat contains ``target.o'' as a target filename.  Such a rule exists in the
Xexample Makefile with dependencies ``source.c'' and ``header.h'', which
Xmust in turn be made before ``target.o'' can be made up to date.  Since
X``source.c'' and ``header.h'' are not defined as targets in the Makefile,
Xthe Make program must use builtin rules of inference to make those files up
Xto date, or it must give up and report that is doesn't know how to make the
Xtarget.  As it turns out, the source and header files are known by builtin
Xrules of inference to require no further action to be made up to date, so
Xthe Make program can continue to make ``target.o'' now that its
Xdependencies have fulfilled their requirements.  In order to make
X``target.o'' up to date, ``command one'' must be executed successfully, and
Xthen ``command two'' must be executed successfully after that.  Finally, the
Xgoal can be made by executing the command line, ``command three'', and the
XMake program will terminate.
X
X
XDEPENDENCIES
X
XIf there are no dependencies for a target, and a target needs to be remade
Xby the Make program, then the target is always remade.  A target with no
Xdependencies will always have its commands executed when that target needs
Xto be remade.
X
XAdditional dependencies can be added to a target defined in another rule by
Xwriting a new rule which declares the additional dependencies.  Only one of
Xthe rules may contain command lines, otherwise it is an error.
X
X
XMACROS and VARIABLES
X
XVariables can contain macro definitions of multiple filenames or other
Xtext.  They are useful for replacing multiple occurrences of the same body
Xof text with references to a variable (macro expansion).  A variable is
Xdefined in the Makefile with an assignment statement.  Only the last
Xassignment of a variable is recognized, because the rules are processed
Xafter the entire Makefile has been interpreted into internal rules by the
XMake program.
X
XIn a makefile, the line:
X
Xmyvariable = source.c header.h
X
Xis used to assign the string ``source.c header.h'' to the variable
Xnamed ``myvariable''.  In the following rule definition:
X
Xtarget.o: $(myvariable)
X
Xthe ``$(myvariable)'' reference is expanded into the string assigned to
X``myvariable''.  If the macro expansion contains further references to
Xother varaiables, then they are also recursively expanded until the
Xresulting string is fully expanded.  Undefined macros are expanded to
Xnothing (empty strings).  ``${myvariable}'' is equivalent to
X``$(myvariable)''.  For single character variable names, the parentheses or
Xbraces are not necessary to expand the macro; the single character may
Ximmediately follow the `$'.
X
XAdditional text can be concatenated to the end of the value of an existing
Xvariable by using the ``+='' operator, like this:
X
Xalpha = abc
Xalpha += def
X
XThe result of ``$(alpha)'' is now ``abc def''.  Notice the space inserted
Xat the point of concatenation.  This ensures that filenames are not split
Xbetween different lines.
X
XIt is possible to define a variable which results in an infinitely
Xrecursive macro expansion.  This is illegal, and it will result in an
Xerror when that variable is referenced.
X
XA variable can be defined, such that its value is expanded immediately at
Xthe time of assignment.  These are called simple variables, and they are
Xassigned with the ``:='' operator.  Note that when a simple variable is
Xassigned, any other references to variables will expand to their value as
Xassigned above the line of the simple variable being assigned.  Here is an
Xexample:
X
Xsimplevar := $(myvariable)
X
XThe only difference between an ordinary variable and a simple variable is
Xthat the value of the simple variable is expanded only once during its
Xassignment, whereas the value of an ordinary variable needs to be
Xexpanded every time it is referenced.  Referencing a simple variable
Xrequires only a simple substitution, whereas referencing an ordinary
Xvariable requires a recursive macro expansion, which requires more work.
X
XVariables referenced in the target and dependencies of a rule are expanded
Xduring the rule definition.  Variables referenced in each command line
Xassociated with a rule are expanded when the command line is executed.
X
XBoth ``\$'' and ``$$'' expand to the character `$'.
X
X
XAUTOMATIC VARIABLES
X
XThere are a set of variables that are automatically defined at runtime by
Xthe Make program.
X
X$@ expands to: target filename
X$* expands to: target filename without its suffix
X$< expands to: the first dependent filename
X$^ expands to: all dependents of target newer than target (not-implemented)
X$% expands to: dependent member of the target archive (not-implemented)
X$? expands to: all dependents of the target archive (not-implemented)
X
XThe value of automatic variables depends on where they are referenced.  An
Xautomatic variable has a different value according to the objects of the
Xrule to which it applies.  $@ does not expand in the target position.
XAutomatic variables making reference to dependencies do not make sense when
Xused in the place of a target name or dependency, so they will not be
Xdefined when referenced in those situations; those variables will expand to
Xtheir proper value in command lines.
X
X
XCOMPLEX VARIABLE NAMES and MACRO EXPANSIONS
X
XRarely is it necessary to apply what is is discussed in this topic, but the
Xinformation will be given for completeness.  Because of the recursive
Xnature of the macro expansion algorithm, it is possible to construct
Xvariables that act like arrays (or other complex data types) through the
Xuse of variable names that themselves contain a nested macro expansion.
XHere is an example of an obscure sort of Makefile that uses this technique:
X
XA1    = one.c
XA2    = two.c
X
Xtarget.o: ${A$(B)}
X    $(CC) -c $(CFLAGS) -o $@ $<
X
XDepending on whether the value of the variable `B' is set to `1' or `2',
Xthe target file will depend on ``one.c'' or ``two.c''.
X
XAlthough there is no strict limit restricting the level to which macros can
Xbe nested (in the variable name and its value), it is recommended that
Xnested be kept to a minimum to conserve on memory consumption and stack
Xusage.  Each level of nesting requires at least an additional 2K of memory.
X
XPlease note that the maximum length of a variable name is 256 characters.
X
X
XFUNCTION CALLS
X
XFunction calls of the form $(function arguments) or ${function arguments}
Xwill be processed differently than a normal macro expansion.  A function
Xcall acts like a macro expansion in that it returns a string.  All spaces,
Xexcept for the sequence of spaces before the first argument (after
Xexpansion), are significant.
X
XPlease note that the maximum length of the string within the parentheses is
X1024 characters.
X
X
XSTRING FUNCTIONS  (see section 9.2 of the GNU Make manual)
X
X$(filter pattern,text)
X
X    A pattern is a word that optionally contains a single wildcard
X    character `%'.  All words in ``text'' that do not match the
X    ``pattern'' are removed, so that this function call returns only
X    matching words.
X
X
X$(filter-out pattern,text)
X
X    All words in ``text'' that match the ``pattern'' are removed, so
X    that this function call returns only non-matching words.  The
X    result is the complement of the result of $(filter).
X
X
X$(findstring find,in)
X
X    if the ``in'' string contains the ``find'' string then the ``find''
X    string is returned, otherwise the result is an empty string
X
X$(patsubst pattern,replacement,text)
X
X    Not implemented yet
X
X$(sort list)
X
X    Not implemented yet
X
X$(strip string)
X
X    strips leading and trailing whitespace from string, and replaces
X    embedded sequences of spaces with a single space.
X
X$(subst from,to,text)
X
X    replaces all occurrences in ``text'' that match ``from'' with the
X    suffix ``to''.  NOTE:  because this is done with a literal
X    substitution, the length of ``from'' must be equal to the length
X    of ``to''.  This limitation is incompatible with GNU Make.
X
X
XFILENAME FUNCTIONS  (see section 9.3 of the GNU Make manual)
X
X$(dir names)
X    Not implemented yet
X
X$(notdir names)
X    Not implemented yet
X
X$(suffix names)
X    Not implemented yet
X
X$(basename names)
X
X    Extracts all but the suffix of each path name in ``names''.  The
X    suffix is the rightmost part of the name starting at the last
X    `.' character.
X
X$(addsuffix suffix,names)
X
X    The result is the list of names with ``suffix'' appended to each
X    word of the list.
X
X$(addprefix prefix,names)
X
X    The result is the list of names with ``suffix'' prepended to each
X    word of the list.
X
X$(join list1,list2)
X    Not implemented yet
X
X$(word n,text)
X
X    Returns the nth word of ``text''.  The first word of text is numbered
X    1, and the last word of text is numbered $(words text).
X
X$(words text)
X
X    Returns the number of words in ``text''.
X
X$(firstword names)
X
X    Returns the first word of ``names''.  The result is the same as
X    $(word 1,names)
X
X$(wildcard pattern)
X
X    The ``pattern'' argument is an Amiga OS wildcard pattern.  The
X    result is a list of files matching that pattern.
X
X    An example of a generic makefile that can be used to compile a
X    program that depends only upon all of the .c files in the
X    current directory follows:
X
X    SRCS := $(wildcard #?.c)
X    OBJS := $(subst .c,.o,$(SRCS))
X
X    a.out:    $(OBJS)
X        $(CC) -o $@ $(CFLAGS) $(OBJS)
X
X
XSPECIAL FUNCTIONS
X
X$(foreach var,list,text)    (see section 9.4 of the GNU Make manual)
X$(origin variable)    (see section 9.5 of the GNU Make manual)
X$(shell command line)    (see section 9.6 of the GNU Make manual)
X
X    None of the above are implemented yet
X
X
XSUFFIX RULES
X
XWhen no explicit rule is defined for a target, the Make program must use
Xother means to determine how to make the target up to date.  Rules of
Xinference are defined by suffix rules.  An example of a double suffix rule
Xis:
X
X.c.o:
X    $(CC) -c $(CFLAGS) -o $@ $<
X.SUFFIXES: .c .o
X
XThe above suffix rule defines how to make any target with a filename ending
Xin ``.o'' if there is a corresponding dependent filename that ends in
X``.c''.  The commands associated with a suffix rule are executed if the
Xdependent file is newer than the target file.
X
XA single suffix rule of the form:
X
X.Z:
X    compress $*
X.SUFFIXES: .Z
X
Xis the same as a double suffix rule, except that there is no dependency
Xsuffix.  As a result, the automatic variable ``$<'' is not defined in the
Xscope of a single suffix rule.  Since there are no dependencies, any target
Xmatching a single suffix rule will always be remade; the commands will
Xalways be executed.
X
XA suffix rule has no dependencies listed to the right of the colon.  If
Xsuch dependencies exist, then the rule definition is not considered a
Xsuffix rule.
X
X
XCOMMAND LINES IN RULES
X
XCommand lines are executed in order of appearance if any dependency is
Xnewer than the target.  The commands executed for a rule should do
Xsomething that causes the modification date to be updated.
X
XThe Make program knows nothing about what the command lines mean or do.
XThe command lines are simply passed to the shell for execution.  If
Xexecuting the command line results in an error, then the Make program will
Xterminate.
X
XSometimes it is desirable to ignore the error returned by a command,
Xbecause failure to execute the command does not affect the successful
Xcompletion of the Makefile.  If this is true then the error returned by a
Xcommand can be ignored by preceding the command with a `-' character.  For
Xexample:
X
Xclean:
X    -delete #?.o
X
XNormally, each command is printed (echoed) before execution.  Echoing for
Xeach command can be disabled by preceding it with a `@' character.  This
Xdoes not affect its execution.  The `@' character does not redirect the
Xstandard output of the program being executed.  Redirection must be
Xstated explicitly.
X
X
XBUILTIN RULES
X
XBy default, the Make program knows several suffix rules.  Here is a list of
Xtheir definitions:
X
X.a:
X.c:
X.h:
X.i:
X.c.o:
X    $(CC) -c $(CFLAGS) -o $@ $<
X.a.o:
X    $(AS) -c $(AFLAGS) -o $@ $<
X.SUFFIXES: .i .h .a .c .o
X
XNotice that assembler and C language headers and source files have no
Xdependencies and require no commands to be executed in order to make them
Xup to date.  User defined rules should be added to the Makefile if that is
Xnot the case.
X
X
XUSER DEFINED BUILTIN RULES
X
XIf the user needs to supplement the internal builtin rules with addition
Xsuffix rules and variable definitions, they can be declared in one of two
Xfiles:  ``S:builtins.make'' or ``builtins.make''.  If they exist, these two
Xfiles are read (in the order listed above) before the Makefile by the Make
Xprogram.  All rules and variables in these files may be referenced (or
Xoveriden) in the Makefile.
X
X
XCONDITIONAL DIRECTIVES
X
XA conditional directive can be used to control which parts of a Makefile
Xare executed, based upon the value assigned to certain variables.  The
Xfamiliar
X
Xif condition
X    ...true...
Xelse
X    ...false...
Xendif
X
Xsyntax is used for this purpose, where ``...true...'' represents any number
Xof lines which are executed if the condition is true, and ``...false...''
Xrepresents any number of lines which are executed if the condition is
Xfalse.  Each of the three conditional directives must appear as the first
Xword on a line.  The ``else'' directive is optional.  The condition may be
Xone of the following:
X
Xeq(arg1,arg2)    true if arg1 is exactly equal to arg2
Xneq(arg1,arg2)    true if arg1 is not equal to arg2
Xdef(variable)    true if variable is defined
Xndef(variable)    true if variable is undefined
X
XNested conditionals are acceptable.  There is no way to perform logical AND
Xand logical OR operations within the condition expression, so nested
Xconditionals will have to be used instead to do the same job.  Each ``if''
Xand ``else'' must have a matching ``endif'' directive associated with its
Xconditional construct.
X
XPRAGMA DIRECTIVE
X
XAny command line arguments may be added to a line beginning in ``pragma''.
XFor example,
X
Xpragma +m2048
X
Xwill set the maximum line length to at least 2048 bytes, if that parameter
Xhas not already been set to a higher value.
X
END_OF_FILE
if test 16057 -ne `wc -c <'bmake.doc'`; then
    echo shar: \"'bmake.doc'\" unpacked with wrong size!
fi
# end of 'bmake.doc'
fi
echo shar: End of archive 3 \(of 3\).
cp /dev/null ark3isdone
MISSING=""
for I in 1 2 3 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 3 archives.
    rm -f ark[1-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0
--
Mail submissions (sources or binaries) to <[e-mail]>.
Mail comments to the moderator at <[e-mail]>.
Post requests for sources, and general discussion to comp.sys.amiga.misc.